home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 August: Tool Chest / Dev.CD Aug 00 TC Disk 1.toast / pc / sample code / files / standard file / standardgetfolder / search.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-06-23  |  9.2 KB  |  250 lines
  1. /*
  2.     File:        Search.h
  3.     
  4.     Description:IndexedSearch and the PBCatSearch compatibility function.
  5.  
  6.     Author:        JL
  7.  
  8.     Copyright:     Copyright: © 1992-1999 by Apple Computer, Inc.
  9.                 all rights reserved.
  10.     
  11.     Disclaimer:    You may incorporate this sample code into your applications without
  12.                 restriction, though the sample code has been provided "AS IS" and the
  13.                 responsibility for its operation is 100% yours.  However, what you are
  14.                 not permitted to do is to redistribute the source as "DSC Sample Code"
  15.                 after having made changes. If you're going to re-distribute the source,
  16.                 we require that you make it clear in the source that the code was
  17.                 descended from Apple Sample Code, but that you've made changes.
  18.     
  19.     Change History (most recent first):
  20.                 6/25/99    Updated for Metrowerks Codewarror Pro 2.1(KG)
  21.  
  22. */
  23.  
  24.  
  25. #ifndef __SEARCH__
  26. #define __SEARCH__
  27.  
  28. #include <Types.h>
  29. #include <Files.h>
  30.  
  31. #include "Optimization.h"
  32.  
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36.  
  37. /*****************************************************************************/
  38.  
  39. pascal    OSErr    IndexedSearch(CSParamPtr pb,
  40.                               long dirID);
  41. /*    ¶ Search in and below a directory.
  42.     The IndexedSearch function performs an indexed search in and below the
  43.     specified directory using the same parameters (in pb) as is passed to
  44.     PBCatSearch. See Inside Macintosh: Files for a description of the
  45.     parameter block.
  46.     
  47.     pb            input:    A CSParamPtr record specifying the volume to search
  48.                         and the search criteria.
  49.                 output:    Fields in the parameter block are returned indicating
  50.                         the number of matches found, the matches, and if the
  51.                         search ended with noErr, the CatPosition record that
  52.                         lets you resume a search where the last search left
  53.                         off.
  54.     dirID        input:    The directory to search. If fsRtDirID is passed,
  55.                         the entire volume is searched.
  56.     
  57.     Note:    If you use a high-level debugger and use ioSearchTime to limit
  58.             the length of time to run the search, you'll want to step over
  59.             calls to IndexedSearch because it installs a Time Manager task.
  60.             Most high-level debuggers don't deal gracefully with interrupt
  61.             driven code.
  62.     
  63.     Result Codes
  64.         noErr                0        No error
  65.         nsvErr                -35        Volume not found
  66.         ioErr                -36        I/O error
  67.         eofErr                -39        End of catalog found (this is normal!)
  68.         paramErr            -50        Parameter block has invalid parameters
  69.                                     (see source for VerifyUserPB) or
  70.                                     invalid catPosition record was passed
  71.         extFSErr            -58        External file system error - no file
  72.                                     system claimed this call.
  73.         memFullErr            -108    Memory could not be allocated in heap
  74.         catChangedErr        -1304    Catalog has changed and catalog position
  75.                                     record may be invalid
  76.     
  77.     __________
  78.     
  79.     See also:    PBCatSearch, PBCatSearchSyncCompat
  80. */
  81.  
  82. /*****************************************************************************/
  83.  
  84. pascal    OSErr    PBCatSearchSyncCompat(CSParamPtr paramBlock);
  85. /*    ¶ Search a volume using PBCatSearch or IndexedSearch.
  86.     The PBCatSearchSyncCompat function uses PBCatSearch (if available) or
  87.     IndexedSearch (if PBCatSearch is not available) to search a volume
  88.     using a set of search criteria that you specify. It builds a list of all
  89.     files or directories that meet your specifications.
  90.     
  91.     pb            input:    A CSParamPtr record specifying the volume to search
  92.                         and the search criteria.
  93.                 output:    Fields in the parameter block are returned indicating
  94.                         the number of matches found, the matches, and if the
  95.                         search ended with noErr, the CatPosition record that
  96.                         lets you resume a search where the last search left
  97.                         off.
  98.     
  99.     Note:    If you use a high-level debugger and use ioSearchTime to limit
  100.             the length of time to run the search, you'll want to step over
  101.             calls to PBCatSearchSyncCompat because it calls IndexedSearch
  102.             which installs a Time Manager task. Most high-level debuggers
  103.             don't deal gracefully with interrupt driven code.
  104.     
  105.     Result Codes
  106.         noErr                0        No error
  107.         nsvErr                -35        Volume not found
  108.         ioErr                -36        I/O error
  109.         eofErr                -39        End of catalog found (this is normal!)
  110.         paramErr            -50        Parameter block has invalid parameters
  111.                                     (see source for VerifyUserPB) or
  112.                                     invalid catPosition record was passed
  113.         extFSErr            -58        External file system error - no file
  114.                                     system claimed this call.
  115.         memFullErr            -108    Memory could not be allocated in heap
  116.         catChangedErr        -1304    Catalog has changed and catalog position
  117.                                     record may be invalid
  118.         afpCatalogChanged    -5037    Catalog has changed and search cannot
  119.                                     be resumed
  120.     
  121.     __________
  122.     
  123.     See also:    PBCatSearch, IndexedSearch
  124. */
  125.  
  126. /*****************************************************************************/
  127.  
  128. pascal    OSErr    NameFileSearch(ConstStr255Param volName,
  129.                                short vRefNum,
  130.                                ConstStr255Param fileName,
  131.                                FSSpecPtr matches,
  132.                                long reqMatchCount,
  133.                                long *actMatchCount,
  134.                                Boolean newSearch,
  135.                                Boolean partial);
  136. /*    ¶ Search for files by file name with PBCatSearch.
  137.     The NameFileSearch function searches for files with a specific file
  138.     name on a volume that supports PBCatSearch.
  139.     Note: A result of catChangedErr means the catalog has changed between
  140.     searches, but the search can be continued with the possiblity that you
  141.     may miss some matches or get duplicate matches.  For all other results
  142.     (except for noErr), the search cannot be continued.
  143.  
  144.     volName            input:    A pointer to the name of a mounted volume
  145.                             or nil.
  146.     vRefNum            input:    Volume specification.
  147.     fileName        input:    The name of the file to search for.
  148.     matches            input:    Pointer to array of FSSpec where the match list is
  149.                             returned.
  150.     reqMatchCount    input:    Maximum number of matches to return    (the number of
  151.                             elements in the matches array).
  152.     actMatchCount    output: The number of matches actually returned.
  153.     newSearch        input:    If true, start a new search. If false and if
  154.                             vRefNum is the same as the last call to
  155.                             NameFileSearch, then start searching at the
  156.                             position where the last search left off.
  157.     partial            input:    If the partial parameter is false, then only files
  158.                             that exactly match fileName will be found.  If the
  159.                             partial parameter is true, then all file names that
  160.                             contain fileName will be found.
  161.     
  162.     Result Codes
  163.         noErr                0        No error
  164.         nsvErr                -35        Volume not found
  165.         ioErr                -36        I/O error
  166.         eofErr                -39        End of catalog found (this is normal!)
  167.         paramErr            -50        Parameter block has invalid parameters
  168.                                     (see source for VerifyUserPB) or
  169.                                     invalid catPosition record was passed
  170.         extFSErr            -58        External file system error - no file
  171.                                     system claimed this call.
  172.         memFullErr            -108    Memory could not be allocated in heap
  173.         catChangedErr        -1304    Catalog has changed and catalog position
  174.                                     record may be invalid
  175.         afpCatalogChanged    -5037    Catalog has changed and search cannot
  176.                                     be resumed
  177.     
  178.     __________
  179.     
  180.     Also see:    CreatorTypeFileSearch
  181. */
  182.  
  183. /*****************************************************************************/
  184.  
  185. pascal    OSErr    CreatorTypeFileSearch(ConstStr255Param volName,
  186.                                       short vRefNum,
  187.                                       OSType creator,
  188.                                       OSType fileType,
  189.                                       FSSpecPtr matches,
  190.                                       long reqMatchCount,
  191.                                       long *actMatchCount,
  192.                                       Boolean newSearch);
  193. /*    ¶ Search for files by creator/fileType with PBCatSearch.
  194.     The CreatorTypeFileSearch function searches for files with a specific
  195.     creator or fileType on a volume that supports PBCatSearch.
  196.     Note: A result of catChangedErr means the catalog has changed between
  197.     searches, but the search can be continued with the possiblity that you
  198.     may miss some matches or get duplicate matches.  For all other results
  199.     (except for noErr), the search cannot be continued.
  200.  
  201.     volName            input:    A pointer to the name of a mounted volume
  202.                             or nil.
  203.     vRefNum            input:    Volume specification.
  204.     creator            input:    The creator type of the file to search for.
  205.                             To ignore the creator type, pass 0x00000000 in
  206.                             this field.
  207.     fileType        input:    The file type of the file to search for.
  208.                             To ignore the file type, pass 0x00000000 in
  209.                             this field.
  210.     matches            input:    Pointer to array of FSSpec where the match list is
  211.                             returned.
  212.     reqMatchCount    input:    Maximum number of matches to return    (the number of
  213.                             elements in the matches array).
  214.     actMatchCount    output: The number of matches actually returned.
  215.     newSearch        input:    If true, start a new search. If false and if
  216.                             vRefNum is the same as the last call to
  217.                             CreatorTypeFileSearch, then start searching at the
  218.                             position where the last search left off.
  219.     
  220.     Result Codes
  221.         noErr                0        No error
  222.         nsvErr                -35        Volume not found
  223.         ioErr                -36        I/O error
  224.         eofErr                -39        End of catalog found (this is normal!)
  225.         paramErr            -50        Parameter block has invalid parameters
  226.                                     (see source for VerifyUserPB) or
  227.                                     invalid catPosition record was passed
  228.         extFSErr            -58        External file system error - no file
  229.                                     system claimed this call.
  230.         memFullErr            -108    Memory could not be allocated in heap
  231.         catChangedErr        -1304    Catalog has changed and catalog position
  232.                                     record may be invalid
  233.         afpCatalogChanged    -5037    Catalog has changed and search cannot
  234.                                     be resumed
  235.     
  236.     __________
  237.     
  238.     Also see:    NameFileSearch
  239. */
  240.  
  241. /*****************************************************************************/
  242.  
  243. #ifdef __cplusplus
  244. }
  245. #endif
  246.  
  247. #include "OptimizationEnd.h"
  248.  
  249. #endif    /* __SEARCH__ */
  250.